<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Using the Debugger via the Command Line Interface
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot079.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot074.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot081.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc192">14.6</A>&nbsp;&nbsp;Using the Debugger via the Command Line Interface</H2><UL>
<LI><A HREF="umsroot080.html#toc114">Counters and Command Arguments</A>
<LI><A HREF="umsroot080.html#toc115">Commands to Continue Execution</A>
<LI><A HREF="umsroot080.html#toc116">Commands to Modify Execution</A>
<LI><A HREF="umsroot080.html#toc117">Display Commands</A>
<LI><A HREF="umsroot080.html#toc118">Navigating among Goals</A>
<LI><A HREF="umsroot080.html#toc119">Inspecting Goals and Data</A>
<LI><A HREF="umsroot080.html#toc120">Changing the Settings</A>
<LI><A HREF="umsroot080.html#toc121">Environment Commands</A>
</UL>

<A NAME="@default806"></A>
This section describe the commands available at the debugger prompt
in the debugger's command line interface (for the graphical user
interface, please refer to the online documentation).<BR>
<BR>
Commands are entered by typing the corresponding key
(without newline), the case of the letters is significant. The action
of some of them is immediate, others require additional parameters to
be typed afterwards. Since the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> debugger has the possibility to
display not only the goal that is currently being executed (the <I>current</I> goal or procedure), but also its ancestors, some of the
commands may work on the <I>displayed</I> procedure whatever it is, and
others on the <I>current</I> one.
<BR>
<BR>
<A NAME="toc114"></A>
<H3 CLASS="subsection"><A NAME="htoc193">14.6.1</A>&nbsp;&nbsp;Counters and Command Arguments</H3>
Some debugger commands accept a counter (a small integer number)
before the command letter (e.g. <B>c</B> creep).
The number is just prefixed to the command and terminated by the
command letter itself. If a counter is given for a command that
doesn't accept a counter, it is ignored.<BR>
<BR>
When a counter is used and is valid for the command,
the command is repeated, decrementing the counter until zero.
When repeating the command, the command and the remaining counter
value is printed after the debugger prompt instead of waiting for user input.<BR>
<BR>
Some commands prompt for a parameter, e.g. the <B>j</B> (<I>jump)</I>
command asks for the number of the level to which to jump.
Usually the parameter has a sensible default value (which is printed
in square backets). If just a newline is typed, then the default value
is taken. If a valid parameter value is typed, followed by newline,
this value is taken. If an illegal letter is typed, the command is aborted.<BR>
<BR>
<A NAME="toc115"></A>
<H3 CLASS="subsection"><A NAME="htoc194">14.6.2</A>&nbsp;&nbsp;Commands to Continue Execution</H3>
All commands in this section continue program execution.
They difference between them is the condition under which execution
will stop the next time. When execution stops again, the next trace
line is printed and a new command is accepted.
<DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><I>n<B>c</B></I> <DD CLASS="dd-list"> <B>creep</B><BR>
<A NAME="@default807"></A>
This command allows exhaustive tracing: the execution stops at the
next port of any leashed procedure. No further parameters are
required, a counter <I>n</I> will repeat the command <I>n</I> times.
It always applies on the current procedure, even when the displayed
procedure is not the current one (e.g. during term inspection).
An alias for the <B>c</B> command is to just type newline (Return-key).<BR>
<BR>
<DT CLASS="dt-list"><I>n<B>s</B></I> <DD CLASS="dd-list"> <B>skip</B><BR>
<A NAME="@default808"></A>
If given at an entry port of a box (CALL, RESUME, REDO), this command skips
the execution until an exit port of this box (EXIT, FAIL, LEAVE).
If given in an exit port it works like <I>creep</I>.
(Note that sometimes the <B>i</B> command is more appropriate, since it
skips to the next port of the current box, no matter which).
A counter, if specified, repeats this command.<BR>
<BR>
<DT CLASS="dt-list"><I>n<B>l</B></I> <DD CLASS="dd-list"> <B>leap</B><BR>
<A NAME="@default809"></A>
Continues to the next spy point (any port of a procedure
which has its spy flag set).
<A NAME="@default810"></A>
A counter, if specified, repeats this command.<BR>
<BR>
<DT CLASS="dt-list"><B>i <I>par</I></B> <DD CLASS="dd-list"> <B>invocation skip</B><BR>
<A NAME="@default811"></A>
Continue to the next port of the box with the invocation number
specified. The default invocation number is the one of the current box.
Common uses for this command are to skip from CALL to NEXT, from NEXT
to NEXT/EXIT/FAIL, from *EXIT to REDO, or from DELAY to RESUME.<BR>
<BR>
<DT CLASS="dt-list"><B>j <I>par</I></B> <DD CLASS="dd-list"> <B>jump to level</B><BR>
<A NAME="@default812"></A>
Continue to the next port with the specified nesting level (which can
be higher or lower than the current one).
The default is the parent's level, i.e. to continue until the current
box is exited, ignoring all the remaining subgoals of the current clause.
This is particularly useful when a <B>c</B> (<I>creep</I>) has been
typed where a <B>s</B> (<I>skip</I>) was wanted.<BR>
<BR>
<DT CLASS="dt-list"><B>n</B> <DD CLASS="dd-list"> <B>nodebug</B><BR>
<A NAME="@default813"></A>
This command switches tracing off for the remainder of the execution.
However, the next top-level query will be traced again.
Use <B>N</B> to switch tracing off permanently.<BR>
<BR>
<DT CLASS="dt-list"><B>q</B> <DD CLASS="dd-list"> <B>query the failure culprit</B><BR>
<A NAME="@default814"></A>
The purpose of this command is to find out why a goal has failed (FAIL)
or was aborted with an exit_block (LEAVE). It prints the invocation
number of the goal which caused the failure. You can then re-run the
program in creep mode and type q at the first command prompt. This will
then offer you to jump to the CALL port of the culprit goal.
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
[eclipse 3]: p.
  (1) 1 CALL  p   %&gt; skip
  (1) 1 FAIL  p   %&gt; query culprit
failure culprit was (3) - rerun and type q to jump there   %&gt; nodebug? [y] 
No (0.00s cpu)

[eclipse 4]: p.
  (1) 1 CALL  p   %&gt; query culprit
failure culprit was (3) - jump to invoc: [3]? 
  (3) 3 CALL  r(1)   %&gt; creep
  (3) 3 FAIL  r(...)   %&gt; creep
  (2) 2 FAIL  q   %&gt; creep
  (1) 1 FAIL  p   %&gt; creep
No (0.01s cpu)
</PRE></BLOCKQUOTE><BR>
<BR>
<DT CLASS="dt-list"><B>v</B> <DD CLASS="dd-list"> <B>var/term modification skip</B><BR>
<A NAME="@default815"></A>
This command sets up a monitor on the currently displayed term,
which will cause a MODIFY-port to be raised on each modification to
any variable in the term. These ports will all have a unique invocation
number which is assigned and printed at the time the command is issued.
This number can then be used with the <B>i</B> command to skip to where
the modifications happen.
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
[eclipse 4]: [X, Y] :: 1..9, X #&gt;= Y, Y#&gt;1.
  (1) 1 CALL  [X, Y] :: 1..9   %&gt; var/term spy? [y] 
Var/term spy set up with invocation number (2)   %&gt; jump to invoc: [1]? 2
  (2) 3 MODIFY  [X{[1..9]}, Y{[2..9]}] :: 1..9   %&gt; jump to invoc: [2]? 
  (2) 4 MODIFY  [X{[2..9]}, Y{[2..9]}] :: 1..9   %&gt; jump to invoc: [2]? 
</PRE></BLOCKQUOTE>
Note that these monitors can also be set
up from within the program code using one of the built-ins
<A HREF="../bips/kernel/debug/spy_var-1.html"><B>spy_var/1</B></A><A NAME="@default816"></A> or
<A HREF="../bips/kernel/debug/spy_term-2.html"><B>spy_term/2</B></A><A NAME="@default817"></A>.<BR>
<BR>
<DT CLASS="dt-list"><B>z <I>par</I></B> <DD CLASS="dd-list"> <B>zap</B><BR>
<A NAME="@default818"></A>
This command allows to skip over, or to a specified port. When this
command is executed, the debugger prompts for a port name (e.g. <B>fail</B>)
or a negated port name (e.g. &sim;<B>exit</B>).
Execution then continues until the specified port appears or,
in the negated case, until a port other than the specified one appears.
The default is the negation of the current port, which is useful
when exiting from a deep recursion (a long sequence of EXIT or FAIL ports).</DL>
<A NAME="toc116"></A>
<H3 CLASS="subsection"><A NAME="htoc195">14.6.3</A>&nbsp;&nbsp;Commands to Modify Execution</H3>
<DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><B>f <I>par</I></B> <DD CLASS="dd-list"> <B>fail</B><BR>
<A NAME="@default819"></A>
Force a failure of the procedure with the specified invocation number.
The default is to force failure of the current procedure.<BR>
<BR>
<DT CLASS="dt-list"><B>a</B> <DD CLASS="dd-list"> <B>abort</B><BR>
<A NAME="@default820"></A>
Abort the execution of the current query and return to the top-level.
The command prompts for confirmation.
</DL>
<A NAME="toc117"></A>
<H3 CLASS="subsection"><A NAME="htoc196">14.6.4</A>&nbsp;&nbsp;Display Commands</H3>
This group of commands cause some useful information to be displayed.
<DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><B>d <I>par</I></B> <DD CLASS="dd-list"> <B>delayed goals</B><BR>
<A NAME="@default821"></A>
Display the currently delayed goals. The optional argument allows
to restrict the display to goal of a certain priority only.
The goals are displayed in a format similar to the trace lines,
except that there is no depth level and no port name.
Instead, the goal priority is displayed in angular brackets:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
[eclipse 5]: [X, Y] :: 1..9, X #&gt;= Y, Y #&gt;= X.
  (1) 1 CALL  [X, Y] :: 1..9   %&gt; creep
  (1) 1 EXIT  [X{[1..9]}, Y{[1..9]}] :: 1..9   %&gt; creep
  (2) 1 CALL  X{[1..9]} - Y{[1..9]}#&gt;=0   %&gt; creep
  (3) 2 DELAY  X{[1..9]} - Y{[1..9]}#&gt;=0   %&gt; creep
  (2) 1 EXIT  X{[1..9]} - Y{[1..9]}#&gt;=0   %&gt; creep
  (4) 1 CALL  Y{[1..9]} - X{[1..9]}#&gt;=0   %&gt; creep
  (5) 2 DELAY  Y{[1..9]} - X{[1..9]}#&gt;=0   %&gt; delayed goals
                                                with prio: [all]? 
------- delayed goals -------
  (3) &lt;2&gt;  X{[1..9]} - Y{[1..9]}#&gt;=0
  (5) &lt;2&gt;  Y{[1..9]} - X{[1..9]}#&gt;=0
------------ end ------------
  (5) 2 DELAY  Y{[1..9]} - X{[1..9]}#&gt;=0   %&gt; 
</PRE></BLOCKQUOTE><BR>
<BR>
<DT CLASS="dt-list"><B>u <I>par</I></B> <DD CLASS="dd-list"> <B>scheduled goals</B><BR>
<A NAME="@default822"></A>
Similar to the <B>d</B> command, but displays only those delayed goals
that are already scheduled for execution.
The optional argument allows
to restrict the display to goal of a certain priority only. Example:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
[eclipse 13]: [X,Y,Z]::1..9, X#&gt;Z, Y#&gt;Z, Z#&gt;1.
  (1) 1 CALL  [X, Y, Z] :: 1..9   %&gt; creep
  (1) 1 EXIT  [X{[1..9]}, Y{[1..9]}, Z{[1..9]}] :: 1..9   %&gt; creep
  (2) 1 CALL  X{[1..9]} - Z{[1..9]}+-1#&gt;=0   %&gt; creep
  (3) 2 DELAY  X{[2..9]} - Z{[1..8]}#&gt;=1   %&gt; creep
  (2) 1 EXIT  X{[2..9]} - Z{[1..8]}+-1#&gt;=0   %&gt; creep
  (4) 1 CALL  Y{[1..9]} - Z{[1..8]}+-1#&gt;=0   %&gt; creep
  (5) 2 DELAY  Y{[2..9]} - Z{[1..8]}#&gt;=1   %&gt; creep
  (4) 1 EXIT  Y{[2..9]} - Z{[1..8]}+-1#&gt;=0   %&gt; creep
  (6) 1 CALL  0 + Z{[1..8]}+-2#&gt;=0   %&gt; creep
  (3) 2 RESUME  X{[2..9]} - Z{[2..8]}#&gt;=1   %&gt; scheduled goals
                                                with prio: [all]? 
------ scheduled goals ------
  (5) &lt;2&gt;  Y{[2..9]} - Z{[2..8]}#&gt;=1
------------ end ------------
  (3) 2 RESUME  X{[2..9]} - Z{[2..8]}#&gt;=1   %&gt; 
</PRE></BLOCKQUOTE><BR>
<BR>
<DT CLASS="dt-list"><B>G</B> <DD CLASS="dd-list"> <B>all ancestors</B><BR>
<A NAME="@default823"></A>
Prints all the current goal's ancestors from the oldest to the newest.
The display format is similar to trace lines,
except that <TT>....</TT> is displayed in the port field.<BR>
<BR>
<DT CLASS="dt-list"><B>.</B> <DD CLASS="dd-list"> <B>print definition</B><BR>
<A NAME="@default824"></A>
If given at a trace line, the command displays the source code of the
current predicate.
If the predicate is not written in Prolog, or has not been compiled from
a file, or the source file is inaccessible, no information can be displayed.<BR>
<BR>
<DT CLASS="dt-list"><B>w</B> <DD CLASS="dd-list"> <B>write source context for current goal</B><BR>
<A NAME="@default825"></A>
Lists the source lines around the current goal displayed by the trace line,
showing the context of the goal. For example: 
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
  (230) 4 CALL  check_word(what, _5824)   %&gt; write source lines
Source file: /homes/user/EclipseTests/Chatq/newtop
  241  :- mode check_words(+,-).
  242  
  243  check_words([],[]).
  244  check_words([Word|Words],[RevWord|RevWords]) :-
  245&gt;    check_word(Word,RevWord),
  245     check_words(Words,RevWords).
  246  
  247  :- mode check_word(+,-).
  248  
   %&gt; 
</PRE></BLOCKQUOTE>
The listing shows the line numbers for the source lines, with a <CODE>&gt;</CODE>
marking the line with the current goal. Note it is the actual body goal
that is shown, rather than the predicate definition as in the `.' command.
An optional numeric argument can be given before the command, specifying
the number of lines surrounding (i.e. before and after) the current goal
that should be listed:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
    %&gt; 2write source lines
Source file: /homes/user/EclipseTests/Chatq/newtop
  243  check_words([],[]).
  244  check_words([Word|Words],[RevWord|RevWords]) :-
  245&gt;    check_word(Word,RevWord),
  245     check_words(Words,RevWords).
  246  
   %&gt; 
</PRE></BLOCKQUOTE>
Source is only shown if the source information is available &ndash; that is, 
the code has to be compiled debuggable from a file, and not all goals have 
source information; for example, goals in meta-calls (e.g. those inside a 
<TT>block/3</TT>). Also, source context cannot be shown at a RESUME port.<BR>
<BR>
<DT CLASS="dt-list"><B>h</B> <DD CLASS="dd-list"> <B>help</B><BR>
<A NAME="@default826"></A>
Print a summary of the debugger commands.<BR>
<BR>
<DT CLASS="dt-list"><B>?</B> <DD CLASS="dd-list"> <B>help</B><BR>
<A NAME="@default827"></A>
Identical to the <B>h</B> command.</DL>
<A NAME="toc118"></A>
<H3 CLASS="subsection"><A NAME="htoc197">14.6.5</A>&nbsp;&nbsp;Navigating among Goals</H3>

While the debugger waits for commands, program execution is always
stopped at some port of some predicate invocation box, or goal.
Apart from this current goal, two types of other goals are also active.
These are the ancestors of the current goal (the enclosing, not yet
exited boxes in the box model) and the delayed goals.
The debugger allows to navigate among these goals and inspect them.
<DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><B>g</B> <DD CLASS="dd-list"> <B>ancestor</B><BR>
<A NAME="@default828"></A>
Move to and display the ancestor goal (or parent) of the displayed goal.
Repeated application of this command allows to go up the call stack.<BR>
<BR>
<DT CLASS="dt-list"><B>x <I>par</I></B> <DD CLASS="dd-list"> <B>examine goal</B><BR>
<A NAME="@default829"></A>
Move to and display the goal with the specified invocation number.
This must be one of the active goals, i.e. either an ancestor of the
current goal or one of the currently delayed goals. 
The default is to return to the current goal, i.e. to the goal at
whose port the execution is currently stopped.
</DL>
<A NAME="toc119"></A>
<H3 CLASS="subsection"><A NAME="htoc198">14.6.6</A>&nbsp;&nbsp;Inspecting Goals and Data</H3>

This family of commands allow the subterms in the goal displayed at the
port to be inspected.
<A NAME="@default830"></A>
The ability to inspect subterms is designed to help overcome two problems
when examining a large goal with the normal display of the goal at a debug
port: 
<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
Some of the subterms may be omitted from the printed goal because
of the print-depth; <BR>
<BR>
<LI CLASS="li-enumerate">If the user is interested in particular subterms, it
may be difficult to precisely locate them from the surrounding arguments,
even if it is printed.
</OL>
With inspect subterm commands, the user is able to issue commands to
navigate through the subterms of the current goal and examine them. 
A <I>current subterm</I> of the goal is maintained, and this is
printed after each inspect subterm command, instead of the entire goal. 
Initially, the current subterm is set to the goal, but this can then be
moved to the subterms of the goal with navigation commands.<BR>
<BR>
Once inspect subterm is initiated by an inspect subterm command, the
debugger enters into the inspect subterm mode. This is indicated in the
trace line by 'INSPECT' instead of the name of the port, and in addition,
the goal is not shown on the trace line:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
        INSPECT  (length/2)   %&gt; 
</PRE></BLOCKQUOTE>
Instead of showing the goal, a summary of the current subterm &ndash; generally its
functor and arity if the subterm is a structure &ndash; is shown in brackets. 
<DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><B>#</B> <I>par</I> <DD CLASS="dd-list"><B>move down to <I>par</I>th argument</B><BR>
The most basic command of inspect subterm is to move the current subterm to
an argument of the existing current subterm. This is done by typing a
number followed by carriage return, or by typing <CODE>#</CODE>, which causes the
debugger to prompt for a number. In both cases, the number specifies the
argument number to move down to.
In the following example, the <CODE>#</CODE> style of the command is used to move
to the first argument, and the number style of the command to move to the
third argument:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
  (1) 1 CALL  foo(a, g(b, [1, 2]), X)   %&gt; inspect arg #: 1&lt;NL&gt;
a
        INSPECT  (atom)   %&gt; 
</PRE></BLOCKQUOTE>
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
  (1) 1 CALL  foo(a, g(b, [1, 2]), X)   %&gt;  3&lt;NL&gt;
X
        INSPECT  (var)   %&gt; 
</PRE></BLOCKQUOTE>
The new current subterm is printed, followed by the INSPECT
trace line. Notice that the summary shows the type of the current
subterm, instead of Name/Arity, since in both cases the subterms are not
structures. <BR>
<BR>
If the current subterm itself is a compound term, then it is possible to
recursively navigate into the subterm:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
  (1) 1 CALL  foo(a, g(b, [1, 2]), X)   %&gt; 2&lt;NL&gt;
g(b, [1, 2])
        INSPECT  (g/2)   %&gt; 2&lt;NL&gt;
[1, 2]
        INSPECT  (list  1-head 2-tail)   %&gt; 2&lt;NL&gt;
[2]
        INSPECT  (list  1-head 2-tail)   %&gt; 
</PRE></BLOCKQUOTE>
Notice that lists are treated as a structure with arity 2, although the
functor (<CODE>./2</CODE>) is not printed.<BR>
<BR>
In addition to compound terms, it is also possible to navigate into the
attributes of attributed variables:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
[eclipse 21]: suspend(foo(X), 3, X-&gt;inst), foo(X).&lt;NL&gt;
  (1) 1 DELAY  foo(X)   %&gt; &lt;NL&gt;
creep
  (2) 1 CALL  foo(X)   %&gt; 1&lt;NL&gt;
X
        INSPECT  (attributes  1-suspend 2-fd )   %&gt;1&lt;NL&gt; 
suspend(['SUSP-1-susp'|_218] - _218, [], [])
        INSPECT  (struct suspend/3)   %&gt; 
</PRE></BLOCKQUOTE>
The variable X is an attributed variable in this case, and when it is the
current subterm, this is indicated in the trace line. The debugger also
shows the user the currently available attributes, and the user can then
select one to navigate into (<CODE>fd</CODE> is available in
this case because the finite domain library was loaded earlier in the
session. Otherwise, it would not be available as a choice here). <BR>
<BR>
Note that the <CODE>suspend/3</CODE> summary contains a <CODE>struct</CODE> before
it. This is because the <CODE>suspend/3</CODE> is a predefined structure with
field names (see section&nbsp;<A HREF="umsroot022.html#chapstruct">5.1</A>). It is possible to view the
field names of such structures using the <CODE>.</CODE> command in inspect mode.<BR>
<BR>
If the number specified is larger than the number of the arguments of the
current subterm, then an error is reported and no movement is made:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
foo(a, g(b, [1, 2]), 3)
        INSPECT  (foo/3)   %&gt; 4&lt;NL&gt;

Out of range.....

foo(a, g(b, [1, 2]), 3)
        INSPECT  (foo/3)   %&gt; 
</PRE></BLOCKQUOTE><BR>
<BR>
<DT CLASS="dt-list"><I>n<B>uparrow key</B></I> <DD CLASS="dd-list"> <B>Move current subterm up by N levels</B><BR>
<A NAME="@default831"></A><BR>
<BR>
<DT CLASS="dt-list"><I>n<B>A</B></I> <DD CLASS="dd-list"> <B>Move current subterm up by N levels</B><BR>
<A NAME="@default832"></A><BR>
<BR>
In addition to moving the current subterm down, it can also be moved up
from its current position. This is done by typing the uparrow key. This key
is mapped to <CODE>A</CODE> by the debugger, so one can also type
<CODE>A</CODE>. Typing <CODE>A</CODE> may be necessary for some configurations
(combination of keyboards and operating systems) because the uparrow key is
not correctly mapped to <CODE>A</CODE>.<BR>
<BR>
An optional argument can preceded the uparrow keystroke, which indicates
the number of levels to move up. The default is 1:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
  (1) 1 CALL  foo(a, g(b, [1, 2]), 3)   %&gt; 2&lt;NL&gt;
g(b, [1, 2])
        INSPECT  (g/2)   %&gt; 1&lt;NL&gt;
b
        INSPECT  (atom)   %&gt; up subterm
g(b, [1, 2])
        INSPECT  (g/2)   %&gt; 1up subterm
foo(a, g(b, [1, 2]), 3)
        INSPECT  (foo/3)   %&gt; 
</PRE></BLOCKQUOTE>
The debugger prints <CODE>up subterm</CODE> when the uparrow key is typed. The
current subterm moves back up the structure to its parent for each level it
moves up, and the above move can be done directly by specifying 2 as the
levels to move up:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
b
        INSPECT  (atom)   %&gt; 2up subterm
foo(a, g(b, [1, 2]), 3)
        INSPECT  (foo/3)   %&gt; 
</PRE></BLOCKQUOTE>
If the number of levels specified is more than the number of levels that
can be traversed up, the current subterm stops at the toplevel:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
  (1) 1 CALL  foo(a, g(b, [1, 2]), 3)   %&gt; 2&lt;NL&gt;
g(b, [1, 2])
        INSPECT  (g/2)   %&gt; 2&lt;NL&gt;
[1, 2]
        INSPECT  (list  1-head 2-tail)   %&gt; 5up subterm
foo(a, g(b, [1, 2]), 3)
        INSPECT  (foo/3)   %&gt; 
</PRE></BLOCKQUOTE><BR>
<BR>
<DT CLASS="dt-list"><B>0</B> <DD CLASS="dd-list"> <B>Move current subterm to toplevel</B><BR>
<A NAME="@default833"></A><BR>
<BR>
It is possible to quickly move back to the top of a goal that is being
inspected by specifying 0 (zero) as the command:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
  (1) 1 CALL  foo(a, g(b, [1, 2]), 3)   %&gt; 2&lt;NL&gt;
g(b, [1, 2])
        INSPECT  (g/2)   %&gt; 2&lt;NL&gt;
[1, 2]
        INSPECT  (list  1-head 2-tail)   %&gt; 2&lt;NL&gt;
[2]
        INSPECT  (list  1-head 2-tail)   %&gt; 2&lt;NL&gt;
[]
        INSPECT  (atom)   %&gt; 0&lt;NL&gt;
foo(a, g(b, [1, 2]), 3)
        INSPECT  (foo/3)   %&gt; 
</PRE></BLOCKQUOTE>
Moving to the top can also be done by the <CODE>#</CODE> command, and not giving
any argument (or <CODE>0</CODE>) when prompted for the argument.<BR>
<BR>
<DT CLASS="dt-list"><I>n<B>leftarrow key</B></I> <DD CLASS="dd-list"> <B>Move current subterm left by N positions</B><BR>
<A NAME="@default834"></A><BR>
<BR>
<DT CLASS="dt-list"><I>n<B>D</B></I> <DD CLASS="dd-list"> <B>Move current subterm left by N positions</B><BR>
<A NAME="@default835"></A><BR>
<BR>
The leftarrow key (or the equivalent <CODE>D</CODE>) moves the current subterm to
a sibling subterm (i.e. fellow argument of the parent structure) that is to
the left of it. Consider the structure <CODE>foo(a, g(b, [1, 2]), 3)</CODE>, then
for the second argument, <CODE>g(b, [1, 2])</CODE>, <CODE>a</CODE> is its (only) left
sibling, and <CODE>3</CODE> its (only) right sibling. For the third argument,
<CODE>3</CODE>, both <CODE>a</CODE> (distance of 2) and
<CODE>g(b, [1, 2])</CODE> (distance of 1) are its left siblings. The optional
numeric argument for the command specifies the distance to the left that
the current subterm should be moved. It defaults to 1.
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
foo(a, g(b, [1, 2]), 3)
        INSPECT  (foo/3)   %&gt; 3&lt;NL&gt;
3
        INSPECT  (integer)   %&gt; 2left subterm
a
        INSPECT  (atom)   %&gt; 
</PRE></BLOCKQUOTE>
If the leftward movement specified would move the argument position before the
first argument of the parent term, then the movement will stop at the first
argument:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
foo(a, g(b, [1, 2]), 3)
        INSPECT  (foo/3)   %&gt; 3&lt;NL&gt;
3
        INSPECT  (integer)   %&gt; 5left subterm
a
        INSPECT  (atom)   %&gt; 
</PRE></BLOCKQUOTE>
In the above example, the current subterm was at the third argument, thus
trying to move left by 5 argument positions is not possible, and
the current subterm stopped at leftmost position &ndash; the first argument.<BR>
<BR>
<DT CLASS="dt-list"><I>n<B>rightarrow key</B></I> <DD CLASS="dd-list"> <B>Move current subterm right by N positions</B><BR>
<A NAME="@default836"></A><BR>
<BR>
<DT CLASS="dt-list"><I>n<B>C</B></I> <DD CLASS="dd-list"> <B>Move current subterm right by N positions</B><BR>
<A NAME="@default837"></A><BR>
<BR>
The rightarrow key (or the equivalent <CODE>C</CODE>) moves the current subterm
to a sibling subterm (i.e. fellow argument of the parent structure) that is
to the right of it. Consider the structure <CODE>foo(a, g(b, [1, 2]), 3)</CODE>,
then for the first argument, <CODE>a</CODE>, <CODE>g(b, [1, 2])</CODE> is a right
sibling with distance of 1, and <CODE>3</CODE> is a right sibling with distance
of 2. The optional numeric argument for the command specifies the distance
to the left that the current subterm should be moved. It defaults to 1.
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
foo(a, g(b, [1, 2]), 3)
        INSPECT  (integer)   %&gt; 2left subterm
a
        INSPECT  (atom)   %&gt; 
</PRE></BLOCKQUOTE>
If the rightward movement specified would move the argument position beyond
the last argument of the parent term, then the movement will stop at the
last argument:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
foo(a, g(b, [1, 2]), 3)
        INSPECT  (foo/3)   %&gt; 3&lt;NL&gt;
3
        INSPECT  (integer)   %&gt; right subterm
3
        INSPECT  (integer)   %&gt; 
</PRE></BLOCKQUOTE>
In the above example, the current subterm was at the third (and last)
argument, thus trying to move to the right (by the default 1 position in
this case) is not possible, and the current subterm remains at the third
argument. <BR>
<BR>
<DT CLASS="dt-list"><I>n<B>downarrow key</B></I> <DD CLASS="dd-list"> <B>Move current subterm down by N levels</B><BR>
<A NAME="@default838"></A><BR>
<BR>
<DT CLASS="dt-list"><I>n<B>B</B></I> <DD CLASS="dd-list"> <B>Move current subterm down by N levels</B><BR>
<A NAME="@default839"></A><BR>
<BR>
The down-arrow key moves the current subterm down from its current
position. This command is only valid if the current subterm is a compound
term and so has subterms itself. A structure has in general more than one
argument, so there is a choice of which argument position to move down to. 
This argument is not directly specified by the user as part of the command,
but is implicitly specified:
the argument position selected is the argument position of the current
subterm within its parent: 
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
foo(a, g(b, [1, 2]), 3)
        INSPECT  (foo/3)   %&gt; 2&lt;NL&gt;
g(b, [1, 2])
        INSPECT  (list  1-head 2-tail)   %&gt; 3down subterm 2 for 3 levels
[]
        INSPECT  (atom)   %&gt; 
</PRE></BLOCKQUOTE>
In the above example, the user moves down into the second argument, and
then use the down-arrow key to move down into the second argument for 2
levels &ndash; the numeric argument typed before the arrow key specified the
number of levels that the current subterm was moved down by.
The command moves into the second argument because it was at the
second argument position when the command was issue. <BR>
<BR>
However, there is not always an argument position for the current
sub-term. For example, when the current sub-term is at the toplevel of the goal
or if it is at an attribute. In these cases, the default for the argument
position to move down into is the first argument: 
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
        INSPECT  (atom)   %&gt; 0&lt;NL&gt;
foo(a, g(b, [1, 2]), 3)
        INSPECT  (foo/3)   %&gt; down subterm 1 for 1 levels
a
        INSPECT  (atom)   %&gt; 
</PRE></BLOCKQUOTE>
In the above example, the down-arrow key is typed at the top-level, and
thus the argument position chosen for moving down is first argument, with
the default numeric argument for the <BR>
<BR>
If the argument position to move into is beyond the range of the current
subterm's number of arguments, then no move is performed:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
  (1) 1 CALL  foo(a, b, c(d, e))   %&gt; 3&lt;NL&gt;
c(d, e)
        INSPECT  (c/2)   %&gt; Out of range after traversing down arg...
c(d, e)
        INSPECT  (c/2)   %&gt; 
</PRE></BLOCKQUOTE>
In this case, the down-arrow key was typed in the second trace line, which
had the current subterm at the third argument of its parent term, and thus
the command tries to move the new current subterm to the third argument of
the current sub-term, but the structure does not have a third argument and
so no move was made. In the case of moving down multiple levels, then the
movement will stop as soon as the argument position to move down to goes
out of range.<BR>
<BR>
Moving down is particularly useful for traversing lists. As discussed,
lists are really structures with arity two, so the #<I>N</I> command would
not move to the <I>N</I><SUP><I>th</I></SUP> element of the list. With the down-arrow command ,
it is possible to move into the <I>N</I><SUP><I>th</I></SUP> position in one command:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
[eclipse 30]: foo([1,2,3,4,5,6,7,8,9]).
  (1) 1 CALL  foo([1, 2, 3, ...])   %&gt; 1&lt;NL&gt;
[1, 2, 3, 4, ...]
        INSPECT  (list  1-head 2-tail)   %&gt; 2&lt;NL&gt;
[2, 3, 4, 5, ...]
        INSPECT  (list  1-head 2-tail)   %&gt; 6down subterm 2 for 6 levels
[8, 9]
        INSPECT  (list  1-head 2-tail)   %&gt; 
</PRE></BLOCKQUOTE>
In order to move down a list, we repeatedly move into the tail of the list
&ndash; the second argument position. In order to do this with the down-arrow
command, we need to be at the second argument position first, and this is
done in the second trace line. Once this is done, then it is possible to
move arbitrarily far down the list in one go, as is shown in the example.<BR>
<BR>
<DT CLASS="dt-list"><B>.</B> <DD CLASS="dd-list"> <B>Print structure definition</B><BR>
<A NAME="@default840"></A><BR>
<BR>
In ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, it is possible to define field names for structures (see
section&nbsp;<A HREF="umsroot022.html#chapstruct">5.1</A>). If the inspector encounters such structures,
then the user can get the debugger to print out the field names. Note that
this functionality only applies within the inspect subterm mode, as the
debugger command `<CODE>.</CODE>' normally prints the source for the predicate. 
The fact that a structure has defined field names are indicated by a
&#8220;struct&#8221; in the summary: 
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- local struct(capital(city,country)).

.....

  (1) 1 CALL  f(capital(london, C))   %&gt; 1&lt;NL&gt;
capital(london, C)
        INSPECT  (struct capital/2)   %&gt; structure definition:
1=city 2=country
   %&gt; 
</PRE></BLOCKQUOTE>
In this example, a structure definition was made for <CODE>captial/2</CODE>. When
this structure is the current subterm in the inspect mode, the
<CODE>struct</CODE> in the summary for the structure indicates that it has
a structure definition. For such structures, the field names are printed by
the structure definition command. <BR>
<BR>
If the command is issued for a term that does not have a structure
definition, an error would be reported:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
        INSPECT  (f/1)   %&gt; structure definition:
No struct definition for term f/1@eclipse.
   %&gt; 
</PRE></BLOCKQUOTE><BR>
<BR>
<DT CLASS="dt-list"><B>p</B> <DD CLASS="dd-list"> <B>Show subterm path</B><BR>
<A NAME="@default841"></A><BR>
<BR>
As the user navigates into a term, then at each level, a particular
argument position (or attribute, in the case of attributed variables) is
selected at each level. The user can view the position the current subterm
is at by the <CODE>p</CODE> command. For example,
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
  (1) 1 CALL  foo(a, g(b, [1, 2]), 3)   %&gt; 2&lt;NL&gt;
g(b, [1, 2])
        INSPECT  (g/2)   %&gt; 2&lt;NL&gt;
[1, 2]
        INSPECT  (list  1-head 2-tail)   %&gt; 1&lt;NL&gt;
1
        INSPECT  (integer)   %&gt; p
Subterm path:  2, 2, 1
   %&gt; 
</PRE></BLOCKQUOTE>
The subterm path shows the argument positions taken at each level of the
toplevel term to reach the current subterm, starting from the top. <BR>
<BR>
Extra information (in addition to the numeric argument position) will be
printed if the subterm at a particular level is either a structure with
field names or an attributed variable. For example:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- local struct(capital(city,country)).

.....

[eclipse 8]: suspend(capital(london, C), 3, C -&gt; inst), f(capital(london, C)).

....

  (2) 1 CALL  f(capital(london, C))   %&gt; 1&lt;NL&gt;
capital(london, C)
        INSPECT  (struct capital/2)   %&gt; 2&lt;NL&gt;
C
        INSPECT  (attributes  1-suspend )   %&gt; 1&lt;NL&gt;
suspend(['SUSP-1-susp'|_244] - _244, [], [])
        INSPECT  (struct suspend/3)   %&gt; 1&lt;NL&gt;
['SUSP-1-susp'|_244] - _244
        INSPECT  (-/2)   %&gt; 
Subterm path:  1, country of capital (2), attr: suspend, inst of suspend (1)
   %&gt;
</PRE></BLOCKQUOTE>
In this example, except for the toplevel argument, all the other positions are
either have field names or are attributes. This is reflected in the path,
for example, <TT>country of capital (2)</TT> shows that the field name for
the selected argument position (2, shown in brackets) is <CODE>country</CODE>,
and the structure name is <CODE>capital</CODE>. For the `position' of the
selected attribute (<CODE>suspend</CODE>) of the attributed variable <CODE>C</CODE>,
the path position is shown as <TT>attr: suspend</TT>.<BR>
<BR>

<H4 CLASS="subsubsection">Interaction between inspect subterm and output modes</H4>
<A NAME="@default842"></A>
The debugger commands that affect the print formats in the debugger also
affects the printed current subterm. Thus, both the print depth and output
mode of the printed subterm can be changed.<BR>
<BR>
The changing of the output modes can have a significant impact on the
inspect mode. This is because for terms which are 
transformed by write macros before they are printed (see
chapter&nbsp;<A HREF="umsroot066.html#chapmacros">12</A>), different terms can be printed depending on the
settings of the output modes. In particular, output transformation is used
to hide many of the implementation related extra fields and even term names
of many ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> data structures (such as those used in the finite domain
library). For the purposes of inspect subterms, the term that is inspected
is always the printed form of the term, and thus changing the output mode
can change the term that is being inspected.<BR>
<BR>
Consider the example of looking at the attribute of a finite domain variable:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
A{[4..10000000]}
        INSPECT  (attributes  1-suspend 2-fd )   %&gt; 2&lt;NL&gt;
[4..10000000]
        INSPECT  (list  1-head 2-tail)   %&gt; 1&lt;NL&gt;
4..10000000
        INSPECT  (../2)   %&gt; 2up subterm
A{[4..10000000]}
        INSPECT  (attributes  1-suspend 2-fd )   %&gt; &lt;o&gt;
current output mode is "QPm", toggle char: T
new output mode is "TQPm".
A{[4..10000000]}
        INSPECT  (attributes  1-suspend 2-fd )   %&gt; 2&lt;NL&gt;
fd(dom([4..10000000], 9999997), [], [], [])
        INSPECT  (struct fd/4)   %&gt; 1&lt;NL&gt;
dom([4..10000000], 9999997)
        INSPECT  (dom/2)   %&gt;
</PRE></BLOCKQUOTE>
After selecting the output mode <CODE>T</CODE>, which turns off any output
macros, the internal form of the attribute is shown. This allows previously
hidden fields of the attribute to be examined by the subterm navigation.
Note that if the current subterm is inside a structure which will be
changed by a changed output mode (such as inside the fd attribute), and the
output mode is changed, then until the current subterm is moved out of the
structure, the existing subterm path is still applicable.<BR>
<BR>
Also, after a change in output modes, the current subterm will still be
examining the structure that it obtained from the parent subterm. Consider
the finite domain variable example again:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
4..10000000
        INSPECT  (../2)   %&gt; up subterm    
[4..10000000]        ***** printed structure 1
        INSPECT  (list  1-head 2-tail)   %&gt; &lt;o&gt;
current output mode is "QPm", toggle char: T
new output mode is "TQPm".
[4..10000000]
        INSPECT  (list  1-head 2-tail)   %&gt; up subterm
A{[4..10000000]}
        INSPECT  (attributes  1-suspend 2-fd )   %&gt; 2
fd(dom([4..10000000], 9999997), [], [], [])
        INSPECT  (struct fd/4)   %&gt; &lt;o&gt;
current output mode is "QPmT", toggle char: T
new output mode is "QPm".
fd(4..10000000, [], [], [])    ***** printed structure 2
        INSPECT  (struct fd/4)   %&gt;      

</PRE></BLOCKQUOTE>
Printed structures 1 and 2 in the above example are at the same position
(toplevel of the finite domain structure), and printed with the same output
mode (<CODE>QPm</CODE>), but are different because the structure obtained from
the parent subterm is different &ndash; in printed structure 2, the output mode
was not changed until after the <CODE>fd/4</CODE> structure was the current
subterm. </DL>
<A NAME="toc120"></A>
<H3 CLASS="subsection"><A NAME="htoc199">14.6.7</A>&nbsp;&nbsp;Changing the Settings</H3>
The following commands allow to change the parameters which
influence the way the tracing information is displayed or processed.
<DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><B>&lt; <I>par</I></B> <DD CLASS="dd-list"> <B>set print depth</B><BR>
<A NAME="@default843"></A>
Allows to modify the <I>print_depth</I>, i.e. the depth up to which
nested argument terms are printed. Everything nested deeper than the
specified depth is abbreviated as <CODE>...</CODE>.
Note that the debugger has a private <I>print_depth</I> setting with
default 5, which is different from the global setting obtained from
<A HREF="../bips/kernel/env/get_flag-2.html"><B>get_flag/2</B></A><A NAME="@default844"></A>.<BR>
<BR>
<DT CLASS="dt-list"><B>&gt; <I>par</I></B> <DD CLASS="dd-list"> <B>set indentation step width</B><BR>
<A NAME="@default845"></A>
Allows to specify the number of spaces used to indent trace lines according
to their depth level. The default is 0.<BR>
<BR>
<DT CLASS="dt-list"><B>m</B> <DD CLASS="dd-list"> <B>module</B><BR>
<A NAME="@default846"></A>
Toggles the module printing in the trace line.
If enabled, the module from where the procedure is called
is printed in the trace line:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
  (1) 1 CALL  true   %&gt; show module
  (1) 1 CALL  eclipse : true   %&gt; 
</PRE></BLOCKQUOTE><BR>
<BR>
<DT CLASS="dt-list"><B>o</B> <DD CLASS="dd-list"> <B>output mode</B><BR>
<A NAME="@default847"></A>
This command allows to modify the options used when printing trace lines.
It first prints the current <TT>output_mode</TT> string, as obtained by
<A HREF="../bips/kernel/env/get_flag-2.html"><B>get_flag/2</B></A><A NAME="@default848"></A>,
then it prompts for a sequence of characters.
If it contains valid output mode flags, the value
of these flags is then inverted.
Typing an invalid character will display a list describing the different
options.
Note that this command affects the global setting of <TT>output_mode</TT>.
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
  (1) 1 CALL  X is length([1, 2, ...])   %&gt; current output mode
                                            is "QPm", toggle char: V
new output mode is "VQPm".
  (1) 1 CALL  X_72 is length([1, 2, ...])   %&gt; current output mode
                                            is "QVPm", toggle char: O
new output mode is "OQVPm".
  (1) 1 CALL  is(X_72, length([1, 2, ...]))   %&gt; current output mode
                                            is "OQVPm", toggle char: .
new output mode is ".OQVPm".
  (1) 1 CALL  is(X_72, length(.(1, .(2, .(...)))))   %&gt; 
</PRE></BLOCKQUOTE><BR>
<BR>
<DT CLASS="dt-list"><B>+</B> <DD CLASS="dd-list"> <B>set a spy point</B><BR>
<A NAME="@default849"></A>
<A NAME="@default850"></A>
Set a spy point on the displayed procedure, the same as using the
<A HREF="../bips/kernel/debug/spy-1.html"><B>spy/1</B></A><A NAME="@default851"></A> predicate.
It is possible to set a spy point on any existing procedure,
even on a built-in on external one.
If the procedure already has a spy point, an error message is printed
and any counter is ignored.<BR>
<BR>
Note that the debugger does not check for spy points that occur inside
skipped procedures or during the execution of any other skip command
than the <I>leap</I> command <B>l</B>.<BR>
<BR>
<DT CLASS="dt-list"><B>&minus;</B> <DD CLASS="dd-list"> <B>remove a spy point</B><BR>
<A NAME="@default852"></A>
<A NAME="@default853"></A>
Similarly to the previous command, this one removes a spy point
from a procedure, if it has one.</DL>
<A NAME="toc121"></A>
<H3 CLASS="subsection"><A NAME="htoc200">14.6.8</A>&nbsp;&nbsp;Environment Commands</H3>
<DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><B>b</B> <DD CLASS="dd-list"> <B>break</B><BR>
<A NAME="@default854"></A>
This command is identical to the
<A HREF="../bips/lib/toplevel/break-0.html"><B>break/0</B></A><A NAME="@default855"></A> call.
A new top-level loop is started with the debugger switched off.
The state of the database and the global settings is the same as
in the previous top-level loop.
After exiting the break level with <CODE>^</CODE>D, or <TT>end_of_file</TT>
the execution returns to the debugger and the last trace line is redisplayed.<BR>
<BR>
<DT CLASS="dt-list"><B>N</B> <DD CLASS="dd-list"> <B>nodebug permanently</B><BR>
<A NAME="@default856"></A>
This command switches tracing off for the remainder of the execution
as well as for subsequent top-level queries. It affects the global
flag <B>debugging</B>, setting it to <I>nodebug</I>.</DL>
<HR>
<A HREF="umsroot079.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot074.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot081.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
